Add hermetic Docker build environment for documentation #21567
Conversation
This adds a Docker-based build system for consistent Jekyll documentation builds across all developers and environments. Changes: - Add Dockerfile with pinned versions (Ruby 3.4, Bundler 4.0, Jekyll 4.3.4) - Add .dockerignore to exclude build artifacts - Add ci/README.md with usage documentation and troubleshooting - Add ci/cloudbuild.yaml for GCP Cloud Build multi-arch builds - Update Makefile with docker-build, docker-serve, docker-shell targets - Update Gemfile with Docker rebuild instructions - Fix _plugins/versions/release_info.rb for Docker path compatibility Image published to: us-docker.pkg.dev/release-notes-automation-stag/docs-builder/docs-builder:latest Usage: make docker-build # Build image locally make docker-serve # Serve docs at http://localhost:4000/docs/ make docker-pull # Pull pre-built image from GCP
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
kikiya
left a comment
kikiya
left a comment
There was a problem hiding this comment.
Confirmed the build works as expected, please update instructions to include memory settings for Rancher.
|
|
||
| ```bash | ||
| # 1. Build the Docker image (first time only) | ||
| make docker-build |
There was a problem hiding this comment.
They don't need to build docker image. Let's keep that as something in our ownership. We will build and publish it. They only need to use it.
There was a problem hiding this comment.
Updated the Quick Start section to use make docker-pull instead of make docker-build. Removed the docker-pull mention from "Other useful commands" since it's now the primary flow.
src/current/Dockerfile
Outdated
| LABEL org.opencontainers.image.description="Hermetic build environment for CockroachDB documentation" | ||
| LABEL org.opencontainers.image.source="https://github.com/cockroachdb/docs" | ||
| LABEL ruby.version="3.4.0" | ||
| LABEL bundler.version="4.0.0" |
There was a problem hiding this comment.
how different is this build environment from Netlify? We may want to keep track of this. If things build locally but not on Netlify it might cause issues.
There was a problem hiding this comment.
Updated the Docker image to match Netlify exactly:
- Ruby: 3.4.0 → 3.2.1 (matches netlify.toml)
- Node.js: 20 LTS → 18.x (matches netlify.toml)
- Bundler: 4.0.0 → 2.7.2 (matches Gemfile.lock)
Added a comment in the Dockerfile noting these versions are kept in sync with netlify.toml. Also added
a note in README.md reminding to update both files together.
There was a problem hiding this comment.
Let's create a simplified readme for docs writers. This one is great for the engineering team. The writers can use a much simpler version that just shows how to use the make files. With the minimal system requirements.
There was a problem hiding this comment.
Restructured the README with a clear separation:
- Top section: Simple Quick Start for docs writers with just docker-pull and docker-serve
- Prerequisites: Added memory requirements for Docker Desktop and Rancher Desktop (8-10 GB RAM)
- Engineering Reference: Moved detailed build/publish instructions below a divider for the engineering team
This reverts commit d1b2b9e.
Add simple instructions for writers to pull and run the docs builder image using Rancher Desktop.
2 participants
Summary
Adds a Docker-based build system to ensure consistent Jekyll documentation builds across all developers and environments. This eliminates "works on my machine" issues by pinning all dependencies.
us-docker.pkg.dev/release-notes-automation-stag/docs-builderLOCAL_DEVELOPMENT.mdat repo root with simple instructions for writersUsage
For writers (see
LOCAL_DEVELOPMENT.md):cd src/current make docker-pull make docker-serveFor engineers:
Test plan
make docker-buildmake docker-serveand verify site loads at localhost:4000/docs/make docker-pullworks with pre-built image from GCP